h1. tween.lua

Small sets of functions for performing tweening in Lua. Based on "jQuery's animate function":http://api.jquery.com/animate/

h1. Examples

<pre>
local tween = require 'tween'

-- increase the volume of music from 0 to 5 in 10 seconds
local music = { volume = 0, path = "path/to/file.mp3" }
tween(10, music, { volume = 5 })

-- make some text fall from the top of the screen, bouncing on y=300, in 4 seconds
local label = { x=200, y=0, text = "hello" }
tween(4, label, { y=300 }, 'outBounce')

-- fade background to black in 2 seconds, and then print a message on the terminal
local backgroundColor = {255,255,255}
tween(2, backgroundColor, {0,0,0}, 'linear', print, "hello!")
</pre>

You will need to put @tween.update@ somewhere in your game loop update function:

<pre>

function your_game_loop_update(dt)
  ...
  tween.update(dt)
  ...
end
</pre>

h1. Interface

* @tween.start(time, subject, target, [easing], [callback], ...)@. By default it Returns an identifier (@id@)
** @time@ will specify how much time must the change will take.
** @subject@ and @target@ must both be tables. @tween.start@ will gradually alter @subject@'s properties until they look like in @target@. Properties not mentioned in @target@ will be ignored.
** @easing@ can be either a function or a function name (see the easing section below). It's default value is @'linear'@
** @callback@ is a function to be called when the tween is over. Only callable objects such as functions are acceptable here. Can be nil.
** Any other parameters are passed to the @callback@ as additional parameters.
* @tween(time, subject, target, [easing], [callback])@ redirect to @tween.start@
* @tween.stop([id])@ stops the animation identified by @id@. It does *not* reset the animation to its initial state.
* @tween.stopAll()@ stops all animations, without resetting any values
* @tween.reset(id)@ stops the animation identified by @id@, and resets its @subject@ to the initial values it had at the start of the animation.
* @tween.resetAll()@ resetd all currently playing animations to their initial state.
* @tween.update(dt)@ is needed to be executed on the main program loop. @dt@ is the amount of time that has passed since the last iteration. When @tween.update@ is executed, the values of very @subject@ are slightly modified so they resemble a bit more their @target@s. It is also the time in which the callbacks are invoked, if they exist.

h1. Gotchas / Warnings

* @tween@ does *not* implement any hardware or software clock; you will have to provide it with the access to the hardware timers, in the form of periodic calls to @tween.update@
* @tween@ does not have any defined time units (seconds, milliseconds, etc). You define the units it uses by passing it a @dt@ on @tween.update@. If @dt@ is in seconds, then @tween@ will work in seconds. If @dt@ is in milliseconds, then @tween@ will work in milliseconds.
* @tween@ can work on deeply-nested subtables (the "leaf" values have to be numbers in both the subject and the target)

<pre>
local trafficLight = { color1 = {255,0,0}, color2 = {0,0,0}, color3 = {0,0,0} }
tween(3, trafficLight, { color1 = {0,0,0}, color2 = {255,255,0}, color3 = {0,0,0} }, 'linear', function()
  tween(1, trafficLight, { color1 = {0,0,0}, color2 = {0,0,0}, color3 = {0,255,0} }
end)
for i=1, 4 do
  tween.update(1) -- In 3 iterations the lights will change from red to yellow. The last iteration will change them to green
end
</pre>

h1. Installation

Just copy the tween.lua file somewhere in your projects (maybe inside a /lib/ folder) and require it accordingly.

Remember to store the value returned by require somewhere! (I suggest a local variable named tween)

<pre>
local tween = require 'tween'
</pre>

The second step is making sure that your "game loop" calls @tween.update@ with a proper @dt@. Where to put this call depends greatly on your game loop architecture. It will probably go into an "update" function:

<pre>
function update(dt)
  ...
  tween.update(dt)
end
</pre>

Also, make sure to read the license file; the text of that license file must appear somewhere in your projects' files.

h1. Easing functions

Easing functions are functions that express how slow/fast the interpolation happens in tween.

tween.lua comes with a lot of easing functions already built-in (adapted from "Emmanuel Oga's easing library":https://github.com/EmmanuelOga/easing

They can be divided into several big families:

* @linear@ is the default interpolation. It's the simplest easing function.
* @quad@, @cubic@, @quart@, @quint@, @expo@, @sine@ and @circle@ are all "smooth" curves that will make transitions look natural.
* The @back@ family starts by moving the interpolation slightly "backwards" before moving it forward.
* The @bounce@ family simulates the motion of an object bouncing.
* The @elastic@ family simulates inertia in the easing, like an elastic gum.

Each family (except @linear@) has 4 variants:
* @in@ starts slow, and accelerates at the end
* @out@ starts fast, and decelerates at the end
* @inOut@ starts and ends slow, but it's fast in the middle
* @outIn@ starts and ends fast, but it's slow in the middle

|_. family |_. in    |_. out     |_. inOut    |_. outIn    |
|_. "linear":https://github.com/kikito/tween.lua/raw/master/graphs/linear.png  |linear   |linear     |linear      |linear      |
|_. "quad":https://github.com/kikito/tween.lua/raw/master/graphs/quad.png      |inQuad   |outQuad    |inOutQuad   |outInQuad   |
|_. "cubic":https://github.com/kikito/tween.lua/raw/master/graphs/cubic.png    |inCubic  |outCubic   |inOutCubic  |outInCubic  |
|_. "quart":https://github.com/kikito/tween.lua/raw/master/graphs/quart.png    |inQuart  |outQuart   |inOutQuart  |outInQuart  |
|_. "quint":https://github.com/kikito/tween.lua/raw/master/graphs/quint.png    |inQuint  |outQuint   |inOutQuint  |outInQuint  |
|_. "expo":https://github.com/kikito/tween.lua/raw/master/graphs/expo.png      |inExpo   |outExpo    |inOutExpo   |outInExpo   |
|_. "sine":https://github.com/kikito/tween.lua/raw/master/graphs/sine.png      |inSine   |outSine    |inOutSine   |outInSine   |
|_. "circle":https://github.com/kikito/tween.lua/raw/master/graphs/circle.png  |inCirc   |outCirc    |inOutCirc   |outInCirc   |
|_. "back":https://github.com/kikito/tween.lua/raw/master/graphs/back.png      |inBack   |outBack    |inOutBack   |outInBack   |
|_. "bounce":https://github.com/kikito/tween.lua/raw/master/graphs/bounce.png  |inBounce |outBounce  |inOutBounce |outInBounce |
|_. "elastic":https://github.com/kikito/tween.lua/raw/master/graphs/elastic.png|inElastic|outElastic |inOutElastic|outInElastic|

You may want to give a look to the graphs folder on this repository to get a better idea of what I'm talking about.

When you specify an easing fucntion, you can either give the function name as a string. The following two are equivalent:

<pre>
tween(10, subject, {x=10}, tween.easing.linear)
tween(10, subject, {x=10}, 'linear')
</pre>

Well, actually, since 'linear' is the default, you can also do this:
<pre>
tween(10, subject, {x=10})
</pre>

You can of course specify your own easing function. Just make sure you respect the parameter format.


h1. Specs

This project uses "telescope":https://github.com/norman/telescope for its specs. If you want to run the specs, you will have to install telescope first. Then just enter the tween.lua folder and run:

<pre>
tsc spec/*
</pre>

h1. Credits

The easing functions have been copied from EmmanuelOga's project in

https://github.com/emmanueloga/easing

See the LICENSE.txt file for details.

